﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" status="Under Construction" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">How to contribute</title>
  <keywords>
    <keyword translate="true">contribute</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">How to contribute</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This topic is meant if you want to contribute. It gives you hints, tools that we use and some coding conventions.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Tools</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">We use the following tools:</text></para>
    <list id="18" type="ul" listtype="bullet" formatstring="&#183;" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="weblink" href="http://tortoisehg.bitbucket.org/" target="_blank" styleclass="Normal (list)" translate="true">TortoiseHg</link><text styleclass="Normal (list)" translate="true"> (for Windows Explorer, see </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://tortoisehg.bitbucket.org/manual/2.0/quick.html" target="_blank" styleclass="Normal (list)" translate="true">this quickstart</link><text styleclass="Normal (list)" translate="true">)</text></li>
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="weblink" href="http://visualhg.codeplex.com/" target="_blank" styleclass="Normal (list)" translate="true">VisualHg</link><text styleclass="Normal (list)" translate="true"> (for Visual Studio)</text></li>
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="weblink" href="http://www.jetbrains.com/resharper/" target="_blank" styleclass="Normal (list)" translate="true">Resharper</link><text styleclass="Normal (list)" translate="true"> (6.1, shared resharper settings are located in the repository)</text></li>
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="weblink" href="http://submain.com/products/ghostdoc.aspx" target="_blank" styleclass="Normal (list)" translate="true">GhostDoc</link><text styleclass="Normal (list)" translate="true"> (for writing documentation)</text></li>
    </list>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Getting the repository</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">First of all, you will need to acquire the source code. You can do this by creating a clone using </text><text styleclass="Normal" style="font-style:italic;" translate="true">TortoiseHg</text><text styleclass="Normal" translate="true">.</text></para>
    <list id="19" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal"><text styleclass="Normal" translate="true">Create a directory called C:\Source\Catel</text></li>
      <li styleclass="Normal"><text styleclass="Normal" translate="true">Right-click on the directory =&gt; TortoiseHg =&gt; Clone...</text></li>
      <li styleclass="Normal"><text styleclass="Normal" translate="true">Use the following information:</text></li>
    </list>
    <para styleclass="Normal"><image src="contribute_mercurial_clone.png" scale="100.00%" styleclass="Image Caption"></image></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Retrieving the repository the first time can take a long time</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">First successful build</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Catel source depends on several existing </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://www.nuget.org" target="_blank" styleclass="Normal" translate="true">NuGet</link><text styleclass="Normal" translate="true"> packages. These packages are not included into Catel repository, so in order to get a first successful build you need to execute a package restore command. This can be done via Package Manager Console loading the </text><text styleclass="Normal" style="font-style:italic;" translate="true">NuGet-Tools.ps1</text><text styleclass="Normal" translate="true"> script file located on </text><text styleclass="Normal" style="font-style:italic;" translate="true">tools\scripts</text><text styleclass="Normal" translate="true"> directory. Then you can execute </text><text styleclass="Normal" style="font-style:italic;" translate="true">Restore-Package</text><text styleclass="Normal" translate="true"> command with switch parameter </text><text styleclass="Normal" style="font-style:italic;" translate="true">-AllProjects</text><text styleclass="Normal" translate="true"> and all packages will be restore from the selected package source.</text></para>
    <para styleclass="Normal"><image src="contribute_nuget_restore.png" scale="100.00%" styleclass="Image Caption"></image></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Getting new updates</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Once you got the initial repository, you want to keep yourself up-to-date as well. This can be done via the workbench. The workbench can be opened by right-clicking on the repository in Windows Explorer and choose &quot;Hg Workbench&quot;. Then choose the </text><text styleclass="Normal" style="font-style:italic;" translate="true">pull</text><text styleclass="Normal" style="font-style:normal;" translate="true"> button:</text></para>
    <para styleclass="Normal"><image src="contribute_mercurial_pull.png" scale="100.00%" styleclass="Image Caption"></image></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Note that it is possible that you have conflicts or need to merge your code. See </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://tortoisehg.bitbucket.org/manual/2.0/quick.html" target="_blank" styleclass="Notes" translate="true">this documentation</link><text styleclass="Notes" translate="true"> for more information</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Writing code</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Well, this is completely up to you. However, keep in mind that we</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">[TODO: DESCRIBE]</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Creating a fork</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">[TODO: DESCRIBE]</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Committing your changes</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Once your changes are ready (of course including unit tests), you can commit your changes. Keep in mind that changes are always committed locally. The advantage is that you decide when the commit becomes available in public. So, you can commit several changes and finally push them all together at once.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To commit changes, right click on the directory (or use </text><text styleclass="Normal" style="font-style:italic;" translate="true">VisualHg</text><text styleclass="Normal" translate="true">) and choose &quot;Hg Commit...&quot;. Then you will see the following window:</text></para>
    <para styleclass="Normal"><image src="contribute_mercurial_commit.png" scale="100.00%" styleclass="Image Caption"></image></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">At the left, select the files you would like to commit. Then, at the right make sure to describe what this commit is all about. It will appear in the changelog so everyone can understand what happened in this commit. Finally, commit using the </text><text styleclass="Normal" style="font-style:italic;" translate="true">Commit</text><text styleclass="Normal" style="font-style:normal;" translate="true"> button.</text></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Keep in mind that once you have committed, the changes are only committed locally, you need to push to publish your commits</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Pushing your changes</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">When all your commits are done, you can push the changes to the actual online repository. You can do this by right-clicking on the repository directory in Windows Explorer, and choose &quot;Hg Workbench...&quot;. Then, you can view all your commits and choose to push them to the server using the surrounded button. You will need a username and password to push your changes.</text></para>
    <para styleclass="Normal"><image src="contribute_mercurial_push.png" scale="100.00%" styleclass="Image Caption"></image></para>
  </body>
</topic>
